package com.wg.net.server.http;

import com.wg.net.annotation.InterceptorOrder;

/**
 * HTTP全局拦截器接口（支持顺序控制、状态管理和生命周期回调）
 *
 * @author 少爷123
 */
public interface HandlerInterceptor {

    /**
     * 业务执行前的逻辑（预处理）
     * <p>
     * 执行前提：请求未被404拦截且处理方法未过期<br>
     * 执行时机：业务方法处理前<br>
     * 执行顺序：按{@link InterceptorOrder}注解的value升序执行<br>
     * 返回值：true=继续后续逻辑；false=中断后续逻辑（不执行postHandle和afterCompletion）
     *
     * @param request  HTTP请求对象
     * @param response HTTP响应对象
     * @return 是否继续后续逻辑
     * @throws Exception 拦截器执行异常（建议捕获后记录日志，避免影响全局）
     */
    boolean preHandle(HttpServletRequest request, HttpServletResponse response) throws Exception;

    /**
     * 业务执行后的逻辑（后处理）
     * <p>
     * 执行时机：业务方法处理完成后（无论成功或失败）<br>
     * 执行顺序：按{@link InterceptorOrder}注解的value升序执行
     *
     * @param request  HTTP请求对象
     * @param response HTTP响应对象
     * @param handler  业务处理器（如Controller方法）
     * @throws Exception 拦截器执行异常
     */
    default void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 默认空实现，支持自定义后处理逻辑
    }

    /**
     * 请求完成后的逻辑（清理阶段）
     * <p>
     * 执行时机：请求完全处理完成（响应已发送）<br>
     * 执行顺序：按{@link InterceptorOrder}注解的value升序执行<br>
     * 适用场景：资源清理（如关闭数据库连接、释放文件句柄）
     *
     * @param request  HTTP请求对象
     * @param response HTTP响应对象
     * @param handler  业务处理器
     * @param ex       业务处理过程中抛出的异常（无异常时为null）
     * @throws Exception 拦截器执行异常
     */
    default void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)
            throws Exception {
        // 默认空实现，支持自定义清理逻辑
    }
}